 /*******************************************************************************
  * Copyright (c) 2003, 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.osgi.framework.console;

 import java.util.Dictionary ;
 import org.osgi.framework.Bundle;

 /**
  * A command interpreter is a shell that can interpret command
  * lines. This object is passed as parameter when a CommandProvider
  * is invoked.
  * <p>
  * This interface is not intended to be implemented by clients.
  * </p>
  * @since 3.1
  */
 public interface CommandInterpreter {
     /**
      * Get the next argument in the input.
      *
      * E.g. if the commandline is hello world, the _hello method
      * will get "world" as the first argument.
      */
     public String nextArgument();

     /**
      * Execute a command line as if it came from the end user
      * and return the result.
      *
      * Throws any exceptions generated by the command that executed.
      */
     public Object execute(String cmd);

     /**
      * Prints an object to the outputstream
      *
      * @param o the object to be printed
      */
     public void print(Object o);

     /**
      * Prints an empty line to the outputstream
      */
     public void println();

     /**
      * Prints an object to the output medium (appended with newline character).
      * <p>
      * If running on the target environment the user is prompted with '--more'
      * if more than the configured number of lines have been printed without user prompt.
      * That way the user of the program has control over the scrolling.
      * <p>
      * For this to work properly you should not embedded "\n" etc. into the string.
      *
      * @param o the object to be printed
      */
     public void println(Object o);

     /**
      * Print a stack trace including nested exceptions.
      * @param t The offending exception
      */
     public void printStackTrace(Throwable t);

     /**
      * Prints the given dictionary sorted by keys.
      *
      * @param dic the dictionary to print
      * @param title the header to print above the key/value pairs
      */
     public void printDictionary(Dictionary dic, String title);

     /**
      * Prints the given bundle resource if it exists
      *
      * @param bundle the bundle containing the resource
      * @param resource the resource to print
      */
     public void printBundleResource(Bundle bundle, String resource);
 }


